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©)  Microtec Research ASM68K 
Assembler, Linker, and Librarian 


Release 6.8D 


introduction 


This document describes the operational changes, enhancements, 
problem corrections, and known problems for the ASM68K 
assembler, linker, librarian, and documentation. This information 
covers changes from release 6.7E through release 6.8D. 


Please fill out your Warranty Registration card and return it to 
Microtec Research. Thank You. 
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es Documentation Errata 


(VMS only) The VAX/VMS section of the ASM68K Users Guide does not document 
how to set up and use the iee2aout utility program. Iee2aout.exe is a foreign image 
and the following DCL command will allow this executable to be invoked. 


ieeZaout :== $ sys$common:[sysexe]iee2aout.exe 


Once this is done, the iee2aout utility will behave as described in the following 
lee2aout Utility section. 


lee2aout Utility 


The ASM68K Users Guide does not fully describe the use of the iee2aout utility. 
This section describes new options that are available with this release as well as 
helpful notes for successful a.out conversions. 


Name 
iee2aout - convert ieee object format to a.out or b.out object format 
Synopsis 
ie iee2aout (-b}[-N]{-ms][-m<magic_num>] <ieee-file> <b.out-file> 
C) Description 


iee2aout converts <ieee-file> absolute file to a.out or b.out format. 


-b Generate b.out instead of a.out. b.out contains more information in the file 
header and has a different default magic number (0415). 


-N_ Use OMAGIC (0407) instead of ZMAGIC (0413) for the executable output 
file. When ZMAGIC is used, the file header is mapped onto the text section. 


-ms Sets the machine type in the magic number for the Sun host. Only valid when 
running on a Sun workstation. 


-m<magic-num> Set the magic number for the output file to 
<magic-num>. <magic-num> is a valid C decimal, octal or hexadecimal 
constant (e.g., -m0407 is the default for relocatables). 


Relocatable file conversion notes 


Tee2aout can only convert files with no more than one section of each type: text, 
data or bss (see section typing below). If no external references are required to be 
Tesolved by the IEEE libraries, then the source files can be compiled with the 
following options to enforce this restriction. 


Co -NCdata -NIdata -NLdata -NSdata -NTtext -NZbss 
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Note older versions of Microtec Research compilers use -Nbss instead of -NZbss. 
Note that the section names can be rearranged as long as the 3-section limit is 
maintained. For example, to include constants, strings and literals in the text 
section, use the following options: 


-NCtext -Nidata -NLtext -NStext -NTtext -NZbss 


Sometimes external references need to be resolved by MRI libraries.This is 
typically the case for targets which do not support operations encountered in the 
source file (e.g., floating point or long division). The compiler generates function 
calls to perform these operations. 


The recommended technique is to compile your source files, then do an incremental 
link to create an object module with the three a.out sections, whose only unresolved 
symbols are defined in non-MRI libraries. This resulting object file can then be 
converted to a.out or b.out format. 


After creating your own MRI library, compile/assemble as you normally would, 
then link and convert as follows: 


Inkxxx -I -0 <output-ieee> -c merge.cmd <input-ieee 1><input-ieee2> 


saaes <your-lib> ( 


iee2aout <output-ieee> <output-aout> 
where merge.cmd contains the following three lines: 


merge text code 
merge data vars,strings,consLliterals ' 
merge bss zerovars 


Example: 


mcc68k -c -g -o filel.iel filei.c 

mcc68k -c -g -o file2.iel file2.c 

Ink68k -r -o file.ie2 -c merge.cmd file.iel file2.ie1 yourlib.lib 
iee2aout file.ie2 file.o 


In this example, the source files "filei.c" and “file2.c" are compiled and a 
relocatable 2.out object file "file.o” is created. 


C++ libraries look for a section named “initfini” to handle static constructors and 

destructors, and sections “ehsftbl" and “ehscfn” to handle exception handling. 

These C++ libraries will not work if these sections are merged into another section. . 
You should not incrementally link one module at a time. You should compile all ) 
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your modules, then incrementally link all the modules into a single 3-sectioned 
IEEE object module and do a single ‘iee2aout’ conversion. Otherwise, modules 
from <your-lib> could become multiply defined. 


Absolute file conversion notes 


Absolute IEEE files are the normal output of the IEEE linker (i.e., run without -r 
option). Iee2aout can handle multiple sections of different types in this case. 
However, <ieee-file> must have all sections of the same a.out type (i.e., text, data 
and bss) grouped together. To do this, include the following lines in the linker 
command file: 


order code,literals,strings,const ;text sections 

order vars,tags.ioports,heap,stack ;data sections 

order zerovars ;bss sections 

sectsize heap=<heapsize> sheap size 

sectsize stack=<stacksize> sstack size (960 only) 


Note that the heap and stack are in the data section. You may wish to modify your 
Start-up code to set the heap and stack at more preferabie locations. 


Section typing 
Sections are typed by IEEE section name or type as follows: 


The following IEEE section names are considered to be text sections: 


text text code 
const strings literals 
initfini ehsftbl ehscfn 


The following IEEE section names are considered to be data sections: 


data data vars 
reserved ioports heap 
. ?2INITDATA tags stack 


The following IEEE section names are considered to be bss sections: 
bss bss zerovars 


Sections with other names are considered text or data according to the IEEE section 
type (i.e., ROM and CODE sections are text, DATA sections are data). Sections 


‘with no IEEE type are considered text with b.out and data with a.out. 
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Installation oO 


Flexible Licensing, Version 2.0 


This product uses Flexible Licensing, Version 2.0, on the following hosts: 


DECStation or DECSystem ULTRIX 4.2 or later 
Sun-3/SunO$S 4.0 or later 

Sun-4/SunOS 4.0 or later 

Apollo DOMAIN/OS 10.3 or later 

IBM RS/6000 AIX version 3.1 or later 

HP 9000/700 or 9000/800 running HP-UX 8.0 or later 


For these hosts, installation instructions appear in the Flexible License Manager 
Documentation Set, (document number 100675-003), which contains an 
Installation Guide and User's Guide. Also, read the Flexible License Manager 
Release Notes (document number 100953-...) for important, recent information. 


System Requirements 
UNIX Systems 


The required operating system versions are named above. @) 
VMS 


You must be running VMS Version 5.1 or later, on any VAX configuration. 


DOS Systems 


The minimum system is an 80286 AT-class PC compatible, running DOS Version 
3.3 or later, with 2 Mb of main plus extended memory. This product is also 
supported on 80386- and 80486-based machines. 


DOS/16M Memory Management System 

The DOS/i6M memory management system is now used by ASM68K, LNK68K, 
and LIB68K on the IBM-PC/DOS host systems. It is transparent to the user except 
that on certain machines, DOS/16M is unable to detect the type of machine present. 
Therefore, the default settings set by DOS/16M do not work. In these special cases, 
you must set a DOS environment variable, that will override the default setting. 


The pos16m environment variable must be set on the following machines as shown —~s 
below: ; () 
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NEC 98-series: 
set DOS16M=1 @start_address-end_address 
Fujitsu FMR-60, 70: 
set DOS16M=$ @start_address-end_address 


AT&T 6300+: 
set DOS16M=6 @start_address-end_address 


The start_address and end_address are numbers, which can be expressed in 
decimal or DOS/16M Memory Management System in hexadecimal format. 
Hexadecimal format requires a ox prefix. The number may end in a x or k to 
indicate an address in kilobytes, or an m or m to indicate megabytes. If no suffix is 
specified, the default is kilobytes. An example of setting the DOS16M environment 
variable on a NEC 9801 is shown below: 


set DOS16M=1 @1m-2m 
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File Placement ‘@) . 


UNIX 


MS-DOS 


VMS 


A complete list of files appears in the file inseall_dir/asm68k/asm68k.fil 
(install_dir is normally /usr/mri). The files are installed in the following 
directories: 


Toolkit Executables install_dir/bin 
Support Files install_dir/asm68k 


A complete list of files appears in the file install. device:-\asm68k\asm68k.fil 
(install_device is normally the C drive). The files are installed in the following 
directory: : 


install_device:\asm68k 


A complete list of files appears in the file ASM68K.FIL in the Support Files 
directory. The files are installed in the following directories: 


Toolkit mages SYS$COMMON:{SYSEXE] e) 
Support Files SYSSCOMMON:[SYSHLP.EXAMPLES.MRI68K] 


56. 


Sa Soll 
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Using 68K tools with XRAY 
Patch68k Utility 


This utility is used to set the internal IEEE chip type. XRA Y68K versions prior to 
version 2.2 will not accept all of the chip types set by the 4.2x MCC68K 
development tools. For example, the most current version of MCC68K uses CPU32 
to represent the 68332 family of processors. If a current version of XRAY68K that 
accepts CPU32 is not available, it may be necessary to patch the chip type with 
68332 using this utility. 


Here is the command line usage for patch68k. 
patch68k <legal_chip_type> <ieee_ftle> 


Where <legal_chip_type> is one of the following: [68000,68010,68020,68332]. 


On VAX/VMS, the patch68k utility exists as a foreign image and the following DCL 
command will allow this executable to be invoked. 


patch68k :== $ sys$common:[sysexe]patch68k.exe 


Once this is done, the patch68k utility will behave as described above. 


Microtec Research ASM68K_ Release 6.8D 


Release 6.8D UO 


Assembler Corrections in 6.8D 


1. (PC only) Using the NOP optimization option, -fopnop, no longer gives a 
protection fault error on source files containing high level debug directives. 


Linker Corrections in 6.8D 


1. Static functions and static variables are now included in the Local Symbol Table 
section of the map file. 


2. The linker can now link an unlimited number of modules. In previous versions, 
exceeding the limit of 500 modules could cause a core dump. 
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Release 6.8A 
_ Operational Changes in 6.8A 


1. 


The ’*’ comment character uséd in linker command files has been replaced by 
the ’;” character. However, ’*’ can still be used as a comment character if it is 
placed in column one. This change was necessary because if the **’ character is 
not in column one it’s usage collides with the use of the ’*’ character in a 
MERGE command. 


The default output format for LNK68K is now IEEE. To change the output 
format, refer to the FORMAT command in the Reference Manual. 


The LNK68K default for local symbol and debug information has been 
changed. The default is now LISTABS INTERNALS. Note, this change will 
cause local symbols to be placed in S-record files. 


(PC only) The startup banner is no longer displayed on each invocation of 
ASM68K and LNK68K. 


. The local symbol table is no longer sorted by default. To sort locals, use the 


optional modifier /BY_NAME with the LISTMAP INTERNALS command. 
For more information, refer to the ASM68K Reference Manual. 


6. The section summary portion of the map file is now presented in address order. 


The linker command file continuation character has been changed from ’+’ to 
‘#. The escape character has been changed from "~’ to "*’. 


Assembler Enhancements in 6.8A 


. The assembler now supports 68049 instructions. 
. Floating-point symbols that are assigned using an FEQU directive will have 


their floating-point values printed out in the symbol table part of the listing file 
as opposed to the string "REAL". 


. Relocatable or absolute sections that are not explicitly typed will have a type 


assigned to them according to the rules specified in Section Type Attributes in 
Chapter 5 of the Reference Manual. 


. The syntax of the ORG directive has been extended to allow absolute sections 


to be named. Please refer to the ORG assembier directive in the ASM68K 
Reference Manual. 


5. The assembler CHIP directive accepts CPU32 as a valid chip type. 
6. The directives IFDEF and IFNDEF have been added to the assembler. For 


more information, refer to the ASM68K Reference Manuai. 


7. Byte relocation is now supported by the assembler. 


8. The new option, -V(/version), displays version and copyright information. 


Microtec Research ASM68K_ Release 6.8D 


Assembler Corrections in 6.8A 


1. 


Positional parameters and local macro labels cannot be placed in the label part 
of an ENDM (macro terminator) directive. The ASM68K Reference Manual has 
been updated to emphasize this. The same effect can be achieved by placing the 
label on the line prior to the ENDM directive. 


2. Assembly language symbols are now case-sensitive by defauit. 


3. Formeriy, FOPT ID=7 was not accepted by the assembler. 


4. A symbol equated to a register can now be used with size qualifiers just like a 


register. 


. The instruction JSR fwdref(Dn) is now accepted as a legal addressing mode 


for 68000. 
(PC only) Formerly, the -I include path option would not work across drives. 


The assembler now generates a warning when extra operands are detected on 
assembler directives. 


(PC only) The banner and error summaries are now displayed on the console, 
regardless of -l and stdout redirection. 


The assembier now generates an error message if a disk drive device becomes 
full. 


. PC-relative addressing modes are now accepted for CMPI when CHIP CPU32 


is specified. 


. Formerly, passing a string containing a space as a macro parameter caused 


improper macro expansion. 


. A label on an odd address and on a line by itself now gets the odd address, rather 


than the address of the next even aligned instruction. 


. Formerly, dc.p 0.0 generated the wrong code for packed decimal 


representation. 


. (VMS only) The /IPATH option was not recognized when the /NOLIST option 


was used. 


Linker Enhancements in 6.8A 
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1. 


2. 


There has been an improvement in the speed of the linker. Local symbols are 
now allocated to a symbol table separate from the public symbols. This results 
in a major performance increase because less memory is allocated to store the 
local symbols and they are not sorted with the public symbols. 


The environment variable MRI_68K_LIB can be used to set the search-path 
that LNK68K will use when looking for libraries and object files for loading. 
The current working directory will always be searched first. 
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9. 


. The linker now generates an entry for the zerovars section in the MODULE 


SUMMARY of the map file. 


. Section names in the SECTION SUMMARY of the map file are no longer 


limited to 8 characters. 


The new SECTSIZE command can be used to change section sizes at link-time. 
Please refer to the manual for more information. 


The new linker commands WARN, ERROR, and NOERROR can be used to 
change the status of certain error messages or warnings. In particular, 
NOERROR can be used to turn off error/warning reporting. Please refer to the 
ASM68K Reference Manual for more information. 


The options -C, -F, -M and -] have been added to the linker. For more 
information on these new features, refer to the ASM68K User's Guide. 


The public symbol! table in the map file can now be sorted by address using the 
optional modifier /BY_ADDR on the LISTMAP PUBLICS command. For 
more information, refer to the ASM68K Reference Manual. 


The linker will now generate an error if no modules are loaded. 


10. A new linker command, LOAD_SYMBOLS, which instructs the linker to only 


load symbols, has been added. Please refer to the ASMO68K Reference Manual 


for more information. 
‘e 11. The 68332 family of processors can now be specified by CPU32. 


12. The linker command PUBLIC symi=sym2+offset is now supported. For more 


information, refer to the ASM68K Reference Manual. 


13. The new option, -V(/version), displays version and copyright information. 
14. A new iee2aout utility has been provided. This conversion utility converts 


IEEE format files into standard a.out format. For VMS , documentation 
concerning this utility has not been provided in the ASM68K User's Guide. 
Please refer to the Documentation Errata section of this document for this 
missing information. 


Linker Corrections in 6.8A 


1. 


The ’+’ character can now be used in comments without causing the linker to 
ignore the next line in the linker command file. 


(VMS only) Long command lines that include long path names no sone 
causes a stack backtrace in the linker. 


(VMS only) Formerly, the absolute IEEE file and map file contained a blank 
module name when specifying the output name with /ABS or /OBJ. 


Using the PUBLIC linker command to set the value of a weak external no 
longer causes a core dump. 


il 
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5. (PC only) The banner is now displayed on the console regardless of stdout { ) 
redirection. 


6. Maximum line length for a linker command file is now 255. The previous 
maximum line length was 105. 


7. (PC only) The error messages are now displayed on the console regardless of 
stdout redirection. 


8. The linker command PUBLIC symJ=sym2, where sym2 is defined in an 
incoming object module, now works correctly. Previously, symZ would get the 
wrong value. 


9, The error "(332) Object contains errors" now specifies the module name. 
10. Formerly, the MERGE command was not compatible with incremental linking. 


11. Formerly, the SIZEOF. operator was not being correctly processed during an 
incremental link. 


12. Formerly, the INITDATA command did not work correctly in conjunction with 
the ABSOLUTE command. 


13. (VMS only) Formerly, a linker option file name given on the command line was 
being truncated at 39 characters. 


Librarian Enhancements in 6.8A O 


1. The new option, -V(/version), displays version and copyright information. 


Librarian Corrections in 6.8A 
1, (VMS only) Previously, the librarian did not work with command line options. 


2. The librarian now generates an error message if a disk drive device becomes 
full. 
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Known Problems 


1. 


6. 
7. 


A negation of a negative floating-point number will not produce a positive 
number. The following example illustrates the defect. 


AA FEQU -1.0 
00000008 F23C 4423 BFRO FMUL.S %-AA,PPO 
0000 


For the DC assembler directive, the evaluation of the Assembly Program 
Counter (denoted by the ‘‘*’’ character) is different from Motorola’s assembler. 
The following example illustrates: , 


MRI 
00000000 1234 0002 R DC.Ww $1234,* 
MOTOROLA 


00000000 1234 0000 R DC.W $1234,* 


A future release of ASM68K will provide a flag for Motorola-compatibility. 
One can use ‘**-2°* as a work-around if Motorola-compatibility is desired. 


The EXTRACT librarian command copies a library module to a file outside the 
library. It must be preceded by an OPEN or a CREATE command. If an error 
occurs prior to the EXTRACT command, the EXTRACT is not inhibited. 


The assembler currently does not allow an external reference (XREF) to take 
the place of a displacement in addressing modes like 


bd{An,Xijor bd(PC,Xi) 
This limitation exists in 68000-mode only. 
The following SECT directive will not cause section ’1’ to be created, unlike 
Motorola’s assembler. Instead, section X is created. 


x EQU 1 
SECT Xx 


. The linker option -Clinker_command will not support INCLUDE file_name 


as the linker_command. : 
The MOVEC instruction is not recognized for CHIP CPU32. 
ASM68K does not allow a ’.’ in a macro name. 
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